Whenever you create a part editor, you must supply OpenDoc with a series of 'nmap' resources, which provide OpenDoc with a multitude of information about your part. When you create a new part using PartMaker, you get a set of 'nmap' resources, which correspond to the kinds of data supported by the part that was used to generate the PartMaker template. You need to change these resources to reflect the information contained in your part.
In addition to the 'nmap' resources, OpenDoc on the Mac OS requires you to specify a unique OSType that corresponds to your part's creator signature. You will also want to add unique icons for your part so that users can distinguish between your part and others. Changing these two things is a matter of manipulating your 'BNDL' resources and setting the appropriate creator type in your development environment.
You need to replace the creator, file type and stationery type in three files.
'sFPJ', ==> 'sXYZ' (Your Stationery File Type (File Type with 's' as first letter))
…
resource 'BNDL' (128) {
'ODFJ', ==> 'ABCD' (Your Creator)
…
data 'ODFJ' (0, "Owner resource") ==> 'ABCD' (Your Creator)
We encourage you to change these identifiers before building your part for the first time.
So the basic checklist of resources to modify is as follows:
- 'nmap' resources
- Mac OS creator type for the part
- Mac OS icons for the part
Modifying Your 'nmap' Resources
Your part can have several 'nmap' resources, depending on the types of data your part supports and the structure of your part editor. The most commonly used 'nmap' resources are as follows:
- Kind->Category mapping
- Editor->Kind mapping
- Editor User String
- Kind User String
- Category User String (only if you do not use an OpenDoc defined category)
- Mac OS Type mapping
In addition, you may want to supply one other type of 'nmap' resource to map platform-types to your part editor, for use during data interchange operations. This Platform Type mapping is described later in this section.
Note: the following examples assume the creation of a sample part called YourPart, which is being developed from a basic PartMaker template. This part supports a custom data format and also supports the data format of another part called SurfPart. This part can also import 'TEXT' and 'PICT' data from standard Mac OS applications.
The OpenDoc Developer Release CDs also have documentation that describes how to create 'nmap' resources for your part. See these documents for more information about 'nmap' resources.
Kind->Category mapping
The Kind->Category mapping allows OpenDoc to map the data format(s) defined by your part to a more generic category, such as Text or Graphics. The basic format of this resource looks like the following:
resource kODNameMappings (kKindCategoryMapId)
{
kODKind,
{
kYourPartKind,
kODIsAnISOStringList
{
{
kODCategoryDrawing,
kYourNewCategory
}
}
}
}
In this example, the kYourPartKind string is an ISO string describing the data format supported by your part. The constant kODCategoryDrawing is defined by OpenDoc as the generic category for object-oriented graphics formats. The kYourNewCategory is a custom category that also describes the part's data. You do not have to support multiple categories in your part, only the ones that make sense for your data.
You must change the text of the kYourPartKind string to match the data format your part supports. You must also change category string(s) to match the category(s) that your part's data falls into.
Editor->Kind mapping
The Editor->Kind mapping allows OpenDoc to map your part editor to the data format(s) it supports in its storage unit. The basic format of this resource looks like the following:
resource kODNameMappings (kEditorKindMapId)
{
kODEditorKinds,
{
kYourPartEditor,
kODIsAnISOStringList
{
{
kYourPartKind,
kSurfPartKind
}
}
}
}
In this example, you would need to change the kYourPartKind string to match your part's data format. Do not change the kYourPartEditor string since PartMaker sets this information correctly when you generate the part.
If your part supports multiple data formats, make sure that you list the formats in order of fidelity, starting with your part's native format.
Editor User String
The Editor User String resource allows OpenDoc to map an instance of your part to a user-readable text string.
resource kODNameMappings (kEditorUserStringMapId)
{
kODEditorUserString,
{
kYourPartEditor,
kODIsINTLText
{
smRoman,
langEnglish,
kEditorUserString
}
}
}
In this example, you would need to change the text of the kEditorUserString to identify your part. This text could contain something like "My Part 1.0".
Kind User String
The Kind User String resource allows OpenDoc to map the kinds of data supported by your part to user-readable strings.
resource kODNameMappings (kEditorUserStringMapId)
{
kODKindUserString,
{
kYourPartKind,
kODIsINTLText
{
smRoman,
langEnglish,
kYourKindUserString
}
}
}
In this example, you would need to change the text of the kYourKindUserString to identify your data. This text would contain something like "My Part data". If you hadn't changed the kYourPartKind string already, you would also need to do that.
Category User String
The Category User String resource allows OpenDoc to map the categories supported by your part to user-readable strings. You do not have to specify this resource if your part uses only OpenDoc standard categories.
resource kODNameMappings (kEditorUserStringMapId)
{
kODKindUserString,
{
kYourNewCategory,
kODIsINTLText
{
smRoman,
langEnglish,
kYourCategoryUserString
}
}
}
In this example, you would need to change the text of the kYourNewCategory and kYourCategoryUserString since they are specific to your part. You do not need to specify a text string for the kODCategoryDrawing category, since OpenDoc defines this string already.
Mac OS Type mapping
The Mac OS Type mapping allows OpenDoc to map the data formats supported by your part to Mac OS types. The basic format of this resource looks like the following:
resource kODNameMappings (kEditorKindMapId)
{
kODKindOldMacOSType,
{
kYourPartKind,
kODIsMacOSType
{
kYourPartMacOSType
},
kSurfPartKind,
kODIsMacOSType
{
kSurfPartMacOSType
},
}
}
In this example, you would need to change the kYourPartMacOSType to match your part's Mac OS type. If you hadn't changed the kYourPartKind string already, you would also need to do that.
Platform Type mapping
In addition to OpenDoc part types, your part can support types such as 'TEXT' and 'PICT', used by existing applications. To do this, you must create a new 'nmap' resource of the type kODEditorPlatformKind. In this resource, specify the OSType's that your part supports. (You must also specify a user string and category for these types in your resource.) The following example shows how you would support both 'TEXT' and 'PICT' resources.
resource kODNameMappings (kEditorPlatformKinds)
{
kODEditorPlatformKind,
{
kYourPartEditor,
kODIsPltfmTypeSpac
{
{
/* First type */
kODPlatformFileType,
kTEXTOSType,
smRoman,
langEnglish,
kDragKindUserString1,
kODCategoryPlainText,
/* Second type */
kODPlatformFileType,
kPICTOSType,
smRoman,
langEnglish,
kDragKindUserString2,
kODCategoryDrawing
}
}
}
}
Changing Your Part Signature
You must define a unique signature that distinguishes your part from other parts. This signature is a four-byte code and is analagous to an application creator type. You specify this signature in your part's 'BNDL' resource and to your development environment when you are building your part. See the documentation that comes with your development environment for setting this signature.
Changing Your Part Icons
There are two places where you need to identify your part's icons: your 'BNDL' resource and your Part Info resource. You can modify your 'BNDL' resource in the same way you would for an application. Your Part Info resource is an ODF custom resource that identifies the icon family that OpenDoc uses to display your part as either a large or small icon within a document.
The Part Info resource contains three pieces of information and looks like the following:
resource FW_RPartInfo(kPartInfoID)
{
// ----- Icon ID
kViewAsIconID,
// ----- Part Name
kEditorUserString,
// ----- PartKind
kYourPartKind
};
See the document "PartInfo Resource" for more information.
